home *** CD-ROM | disk | FTP | other *** search
/ Software Vault: The Diamond Collection / The Diamond Collection (Software Vault)(Digital Impact).ISO / cdr48 / 386p_200.zip / 386MENU.TXT < prev    next >
Text File  |  1994-10-27  |  12KB  |  282 lines
  1.  
  2. ; A 386 MENU definition is a sequence of menu entries (read bytes and dwords)
  3. ; these data structure will evolve from release to release
  4. ; but will always be backward compatible.
  5. ;
  6. ; MENU DATA IS BYTE ALIGNED
  7. ; (remember to write ALIGN BYTE before every menu definition!!!)]
  8. ;
  9. ; Every menu entry is defined as:
  10. ;  a FOUR BYTES HEADER  (four bytes into a DWORD!!!!!!) containing
  11. ;  the menu_type byte plus other three bytes with optional informations
  12. ;  (usually column positions and input field lenght)
  13. ;
  14. ; after those mandatory four bytes, there are one or more DWORDS
  15. ; with data depending on the menu type.
  16. ; (usually these dwords are offsets pointing to actual data)
  17. ;
  18. ; The FIRST menu entry must be of M_HEADER type (the menu title)
  19. ; and the LAST must be of M_END type ( the end of menu marker plus
  20. ; pointers to optional text).
  21. ;
  22. ; So a menu will always look like:
  23. ;
  24. ;               MENU TITLE
  25. ;           ->  entry 1  entry_value
  26. ;               entry 2  entry_value
  27. ;               ......
  28. ;               entry n  entry_value
  29. ;               EXPLANATORY TEXT (optional)
  30. ;
  31. ; the M_HEADER contains a field containing the maximum "menu width"
  32. ; expressed in characters, so the menu handling software can decide
  33. ; on the flight what character size it can use.
  34. ; The menu height in character depend on how many entries there are
  35. ; and how many lines of "explanatory text" are present in the
  36. ; M_END entry.
  37. ;
  38. ; YOU CAN TRUST A MAXIMUM WIDTH OF 38 CHARACTERS IS ALWAYS POSSIBLE
  39. ; AND A MAXIMUM HEIGHT OF 25 LINES, DO NOT EXCEED THIS.
  40. ; BECAUSE OF THE 25 LINES OF TEXT LIMIT
  41. ; THERE CAN BE UP TO (22 - LINES_OF_ENDING_TEXT) MENU ENTRIES.
  42. ; (there is at least an interline between title, entries and ending text)
  43. ; As a rule of thumb, better do not exceed 10 menu entries and 5 lines of
  44. ; ending text.
  45.  
  46. ; And now, more explanations..
  47. ;
  48. ; The following menu entries are described using this layout:
  49. ; ENTRY_NAME         ENTRY_TEXT ENTRY_VALUE             COMMENTS
  50. ;
  51. ;           ENTRY_DEFINITION
  52. ;
  53. ; EXTRA DESCRIPTIONS
  54.  
  55. ;
  56. ; Header:            text                               menu title
  57. ;
  58. ;       db M_HEADER,t_col,maxwidth,touchngo
  59. ;       dd text_p,x,y
  60. ;
  61. ;   x,y    = initial position IN PIXELS of the upper left border
  62. ;            of this menu, or -1,-1 if the menu manager can freely choose
  63. ;            where popup these.
  64. ;            N.B. if x,y are out of range or the menu manager supports
  65. ;                 popup menu repositioning, these values will be
  66. ;                 modified by the menu manager.
  67. ;   t_col  = column position of entry name
  68. ;   text_p = code32 offset to asciiz string to show starting from
  69. ;            t_col column.
  70. ;   maxwidth = maximum menu width in characters
  71. ;   touchngo: 0 = only ESC or selection of an "exit" entry will end this menu
  72. ;             1 = AFTER the fisrt selection of an entry this menu will end
  73. ;             (useful to implement "save game" or "load game" menu)
  74.  
  75. ; Bar:               text  <-]#############[+>          a "volume level" bar
  76. ;
  77. ;       db M_BAR,t_col,in_col,in_len
  78. ;       dd text_p, value_p, func_p, min, max, step
  79. ;
  80. ;   in_col  = colum position of the "volume level bar"
  81. ;             starting with the <-] character
  82. ;   in_len  = lenght of the "volume bar" (excluding the <-] and [+> characters)
  83. ;   value_p = code32 offset to the variable containing the value to show/set
  84. ;   min     = minimum allowed value
  85. ;   max     = maximum allowed value
  86. ;   func_p  = code32 offset of function to call every time the entry value
  87. ;             is altered (use this for value checking/correction
  88. ;             or to trigger special actions depending on the value )
  89. ;             Function parameters:
  90. ;                       in:
  91. ;                       Segment registers pointing to the usual 386P segments.
  92. ;                       EAX = value "requested by user"
  93. ;                             to set into the variable pointed by value_p
  94. ;                       out:
  95. ;                       EAX = ALLOWED value to store into the variable
  96. ;                             (the menu manager will store it properly)
  97. ;                       IF carry set  THEN
  98. ;                               "refresh" completely this menu
  99. ;                               (useful to show messages)
  100. ;                       END IF
  101. ;                       All other registers preserved.
  102. ;
  103. ;   step    = increment/decrement step for the variable pointed by value_p
  104. ;
  105.  
  106. ; Int:               text  <-]_____________[+>          a 32bit integer value
  107. ;
  108. ;       db M_INT,t_col,in_col,idigits
  109. ;       dd text_p, value_p, func_p, min, max, step
  110. ;
  111. ;       idigits = maximum number of digits including optional sign character
  112.  
  113. ;
  114. ; Unsigned:          text  <-]_____________[+>          a 32bit dword value
  115. ;
  116. ;       db M_UNSIGNED,t_col,in_col,udigits
  117. ;       dd text_p, value_p, func_p, min, max, step
  118. ;
  119. ;        udigits = maximum number of digits (and no sign)
  120.  
  121. ;
  122. ; Pick_list:         text  <-]_____________[+>          choose from a list
  123. ;
  124. ;       db M_PICK,t_col,in_col,max_item_len
  125. ;       dd text_p, value_p, func_p, picklist_p, picktop
  126. ;
  127. ;       max_item_len = maximum lenght in characters of the strings
  128. ;                      pointed by the "pick list" table
  129. ;                      (EVERY STRING pointed by the picklist must have this
  130. ;                       lenght (ecluding the final NUL).
  131. ;       value_p = pointer to a dword with values ranging
  132. ;                 from 0         (for the first picklist string)
  133. ;                 to   picktop-1 (for the last  picklist string).
  134. ;       picklist_p = pointer to a list of pointers (all code32 offsets)
  135. ;                    to strings describing the "values" you can choose
  136. ;                    i.e: if  piclist_p    contains offset choose_level
  137. ;                         and picktop      contains 5
  138. ;                         and max_item_len contains 28
  139. ;                         somewere there will be:
  140. ;
  141. ;                         choose_level dd offset easy        ; 0
  142. ;                                      dd offset normal      ; 1
  143. ;                                      dd offset hard        ; 2
  144. ;                                      dd offset very_hard   ; 3
  145. ;                                      dd offset impossible  ; 4
  146. ;
  147. ;                         easy       db 'KINDERGARDEN MODE      ',0
  148. ;                         normal     db 'NOT A PROBLEM          ',0
  149. ;                         hard       db 'GOOD ENOUGH            ',0
  150. ;                         very_hard  db 'TOUGH ENOUGH!          ',0
  151. ;                         impossible db 'BAD,UGLY AND DANGEROUS!',0
  152. ;
  153. ;
  154. ; String:            text  _____________                string entry
  155. ;
  156. ;       db M_STRING,t_col,in_col,max_string_characters
  157. ;       dd text_p, value_p, sfunc_p,
  158. ;
  159. ;       sfunc_p == same parameter convention as into bar entries but remember
  160. ;                  this time the value passed is a POINTER.
  161. ;                  (so you can't change it, but you can change the bytes
  162. ;                   pointed by it)
  163. ;
  164. ; Submenu:           text                               call a submenu
  165. ;
  166. ;       db M_MENU,t_col,thru,m_disable
  167. ;       dd text_p, menu_p
  168. ;
  169. ;       menu_p = code32 offset of M_HEADER entry of menu to call
  170. ;                when this entry is clicked.
  171. ;       thru :  0 = when returning, reactivate this menu and refresh screen
  172. ;               1 = when returning, quit this menu automatically.
  173. ;       m_disable: 0= this submenu can be activated
  174. ;                  1= submenu disabled
  175. ;
  176. ; Call:           text                               call a subroutine
  177. ;
  178. ;       db M_CALL,t_col,thru,0
  179. ;       dd text_p, procedure_p
  180. ;
  181. ;       procedure_p = code32 offset of code to call
  182. ;                     when this entry is clicked.
  183. ;                     The function assumes cs=_SelCode, ds=es=ss=fs=_SelData
  184. ;                     gs=_SelZero, like the _PopMenu procedure.
  185. ;                     The called procedure must preserve all registers.
  186. ;
  187. ; Toggle:            [] text                            boolean entry
  188. ;
  189. ;       db M_TOGGLE,t_col,flag_col,0
  190. ;       dd text_p, bool_p, func_p,
  191. ;
  192. ;       flag_col = column position of '[]' on/off character
  193. ;       bool_p   = pointer to BYTE that can be toggled to 0 or to 1
  194. ;                  when clicking on this entry.
  195. ;
  196. ; Key:               text  keytext                      keyboard key value
  197. ;
  198. ;       db M_KEY,t_col,key_col,0
  199. ;       dd text_p, key_p, func_p
  200. ;
  201. ;       key_col = column position of TEXT (obtained from _KeyNames)
  202. ;                 describing the key.
  203. ;       key_p   = pointer to BYTE that contains the key code
  204. ;       func_p  = pointer to function the menu system will call
  205. ;                       to check if the selected character is correct
  206. ;                       (example:
  207. ;                             in a keyboard-emulated joystick setup routine
  208. ;                             you want different characters for every
  209. ;                             "direction" or "button")
  210. ;                       in:  eax = character code
  211. ;                       out: eax = allowed code
  212. ;                                  ( 0 if you want make the user retry
  213. ;                                    with another key )
  214. ;                            IF (CARRY SET) AND (EAX!=0) THEN
  215. ;                                     refresh all the displayed data
  216.  
  217. ; Exit:              text                               "exit from this menu"
  218. ;
  219. ;       db M_EXIT,t_col,0,0
  220. ;       dd exit_text_p
  221. ;
  222. ;       exit_text_p = pointer to the entry name
  223. ;                     (for example:  'CONTINUE GAME',0)
  224. ;
  225. ; End:               etext                              end menu marker
  226. ;                    etext                              with optional text
  227. ;                    ....
  228. ;                    etext
  229. ;
  230. ;       db M_END,t_col,t_lines,0
  231. ;       dd etext_p
  232. ;
  233. ;       t_lines = lines of text/string count of strings pointed by etext_p
  234. ;
  235. ;       etext_p = pointer to  a table of pointers to asciiz text strings
  236. ;                 to show on the bottom of the menu
  237. ;                  if ( etext_p == 0 ) then no text
  238. ;                 For example:
  239. ;                       if etext_p  contains offset menu_usage
  240. ;                       and t_lines contains 4
  241. ;                       and there is:
  242. ;
  243. ;                       menu_usage dd e0,e1,e2,e3,e4,e5
  244. ;
  245. ;                           e0    db ' HOW',0
  246. ;                           e1    db '  MANY',0
  247. ;                           e2    db '   LINES',0
  248. ;                           e3    db 'YOU',0
  249. ;                           e4    db 'WILL',0
  250. ;                           e5    db '  SEE?',0
  251. ;
  252. ;                       You will see on the bottom of the menu:
  253. ;                               HOW
  254. ;                                MANY
  255. ;                                 LINES
  256. ;                              YOU
  257. ;
  258. ;                       (the other strings are not displayed)
  259.  
  260. ;  YOU CAN WRITE on the "ending text strings"
  261. ;  (or simply you can change the pointers into the table)
  262. ;  to display new messages or show "non alterable" info.
  263. ;  (use the func_p entries to check entry values and change the ending text
  264. ;   according on what happened).
  265.  
  266. You may wonder why i used pointers (actually 32bit offsets)
  267. to variables and text instead of embedding 'em into the menu.
  268. The reason is quite simple, using offsets you can "bolt on" a menu
  269. "above" existing code, and LET THE MENU TEXT SELF-CONFIGURE
  270. (more on this later into INTERNATIONAL.TXT ).
  271.  
  272. Another thing you have to remember is that the menu definition must
  273. be backward compatible, and that the MENU HANDLING MODULE may change!!!!
  274. The current 386menu module is designed for 320x200 screens
  275. but if you want, you can make a menu handler for 80x25 text screens
  276. or for svga screen resolutions.
  277. The current 386menu module will work with any video mode
  278. with 320x200 resolution or higher, but on higher resolutions
  279. it will usually appear in the upper left corner with tiny characters
  280. (if you want something fancier, code it).
  281.  
  282.